\r\n\tThis is a tool for obtaining code coverage information, i.e.\r\n\tinformation about which points in the code were executed how\r\n\toften during a particular run of the program.\r\n
\r\n\tThe usage is as follows:\r\n\t
\r\n\t?- lib(coverage).\r\n\t\r\n\t
\r\n\t?- coverage:ccompile(my_program).\r\n\t\r\n\t
\r\n\t?- my_query(X,Y,Z).\r\n\t\r\n\t
\r\n\t?- coverage:result(my_program).\r\n\t\r\n\t
\r\n\tBy default, code coverage counters are inserted before and after\r\n\tevery subgoal in the code. For instance, in the clause\r\n
\r\n\tp :- q, r, s.\r\n\r\n\tfour counters would be inserted: before the call to q, between\r\n\tq and r, between r and s, and after s:\r\n
\r\n\tp :- point(1), q, point(2), r, point(3), s, point(4).\r\n\r\n\tThis is the most precise form provided. The counter values do not\r\n\tonly show whether all code points were reached, they also show whether\r\n\tsubgoals ever failed or aborted (in that case the counter before\r\n\ta subgoal will have a higher value than the counter after it).\r\n\tFor example, the result of running the above code may look like:\r\n
\r\n\tp :- 43 q, 25 r, 25 s 0 .\r\n\r\n\twhich would indicate that q was called 43 times, but succeeded\r\n\tonly 25 times, r was called 25 times and succeeded always, and\r\n\ts was called 25 times and never succeeded. Coverage counts of\r\n\tzero are displayed in red because they indicate unreached code.\r\n
\r\n\tIf one is only interested in knowing whether all code was covered,\r\n\tit is not necessary to have all these counters. point(1) and point(4)\r\n\tare enough to know whether q, r and s were successfully executed.\r\n\tThe option blocks_only implements this: counters only\r\n\tget inserted at the beginning and at the end of conjunctions\r\n\t(comma-separated goal sequences), i.e. in the example:\r\n
\r\n\tp :- point(1), q, r, s, point(4).\r\n\r\n\tFor big programs, the presence of counters at the end of\r\n\tclauses can cause problems because they prevent tail-recursion\r\n\toptimization and may lead to stack overflows. If that should\r\n\tbe the case, exit-counters can be disabled by setting the\r\n\texit_counters option to off, leading to the following\r\n\tincomplete instrumentation:\r\n
\r\n\tp :- point(1), q, point(2), r, point(3), s.\r\n\r\n
\r\n\tNote on the analysis of large, structured applications: \r\n\tLarger applications often consist of several modules which get\r\n\tcompiled implicitly through use_module/1 directives. In this\r\n\tcase, the module(s) that one wants to compile in coverage mode\r\n\tcan be either compiled with ccompile/1 in advance (before\r\n\tloading the main application module), or afterwards (in which\r\n\tcase ccompile/1 will replace the previously compiled normal\r\n\tcode with coverage-code).\r\n
\r\n\tLimitation: The current implementation cannot deal with multiple\r\n\t(non-module) files that are ccompiled into the same module.\r\n
")). :- comment(ccompile / 1, [summary : "Compile a file, inserting code coverage counters", args : ["File" : "Atom or string"], amode : ccompile(+), see_also : [ccompile / 2, library(coverage), result / 1, result / 2], desc : html("\r\n This is a variant of the ECLiPSe compiler that inserts code coverage\r\n counters into the compiled code. This code can then be run, and the\r\n results analysed by printing them using coverage:result/1.\r\n ")]). :- comment(ccompile / 2, [summary : "Compile a file, inserting code coverage counters", args : ["File" : "Atom or string", "OptionList" : "List of Name:Value pairs"], amode : ccompile(+, +), see_also : [ccompile / 1, library(coverage), result / 1, result / 2], desc : html("\r\n This is a variant of the ECLiPSe compiler that inserts code coverage\r\n counters into the compiled code. This code can then be run, and the\r\n results analysed by printing them using coverage:result/1.\r\n
\r\n Options to modify the behaviour of the code coverage library are:\r\n
\r\n This will pretty-print all source files that have been previously\r\n compiled with ccompile/1,2. For details see result/1.\r\n
\r\n ")]). :- comment(result / 1, [summary : "Pretty-print a file, including any code coverage results", args : ["File" : "Atom or string"], amode : result(+), see_also : [result / 2, library(coverage), library(pretty_printer), ccompile / 1], desc : html("\r\n This will pretty-print the given source file, annotated with the\r\n values of code coverage counters. The resulting .html file will be\r\n placed in a sub-directory called 'coverage', relative to File.\r\n See result/2 for options to modify the output.\r\n
\r\n This predicate only makes sense if File has previously been compiled\r\n in coverage mode (using coverage:ccompile/1,2), and the code has been\r\n run in order to obtain values for the coverage counters.\r\n
\r\n ")]). :- comment(result / 2, [summary : "Pretty-print a file, including any code coverage results", args : ["File" : "Atom or string", "OptionList" : "List of Name:Value pairs"], amode : result(+, +), see_also : [result / 1, pretty_printer : pretty_print / 2, ccompile / 1, library(coverage), library(pretty_printer)], desc : html("\r\n This will pretty-print the given source file, annotated with the\r\n values of code coverage counters. By default, the resulting .html\r\n file will be placed in a sub-directory called 'coverage', relative\r\n to File.\r\n
\r\n OptionList is a list of options identical to the one accepted by\r\n pretty_print/2 in the library(pretty_printer), and can be used to\r\n modify the output style and the location of the output file.\r\n
\r\n This predicate only makes sense if File has previously been compiled\r\n in coverage mode (using coverage:ccompile/1,2), and the code has been\r\n run in order to obtain values for the coverage counters.\r\n ")]). :- comment(result_body / 3, hidden). :- comment(result_body / 2, hidden). :- comment(ccompile_body / 3, hidden). :- comment(ccompile_body / 2, hidden). :- comment(point / 2, hidden).